home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 2002 November / SGI Freeware 2002 November - Disc 1.iso / dist / fw_cvs.idb / usr / freeware / info / cvs.info-3.z / cvs.info-3
Text File  |  2002-01-08  |  50KB  |  1,258 lines
  1. This is cvs.info, produced by makeinfo version 4.0 from cvs.texinfo.
  2.  
  3. START-INFO-DIR-ENTRY
  4. * CVS: (cvs).          Concurrent Versions System
  5. END-INFO-DIR-ENTRY
  6.  
  7.    Copyright (C) 1992, 1993 Signum Support AB Copyright (C) 1993, 1994
  8. Free Software Foundation, Inc.
  9.  
  10.    Permission is granted to make and distribute verbatim copies of this
  11. manual provided the copyright notice and this permission notice are
  12. preserved on all copies.
  13.  
  14.    Permission is granted to copy and distribute modified versions of
  15. this manual under the conditions for verbatim copying, provided also
  16. that the entire resulting derived work is distributed under the terms
  17. of a permission notice identical to this one.
  18.  
  19.    Permission is granted to copy and distribute translations of this
  20. manual into another language, under the above conditions for modified
  21. versions, except that this permission notice may be stated in a
  22. translation approved by the Free Software Foundation.
  23.  
  24. 
  25. File: cvs.info,  Node: Tags,  Next: Tagging the working directory,  Prev: Assigning revisions,  Up: Revisions
  26.  
  27. Tags-Symbolic revisions
  28. =======================
  29.  
  30.    The revision numbers live a life of their own.  They need not have
  31. anything at all to do with the release numbers of your software
  32. product.  Depending on how you use CVS the revision numbers might
  33. change several times between two releases.  As an example, some of the
  34. source files that make up RCS 5.6 have the following revision numbers:
  35.  
  36.      ci.c            5.21
  37.      co.c            5.9
  38.      ident.c         5.3
  39.      rcs.c           5.12
  40.      rcsbase.h       5.11
  41.      rcsdiff.c       5.10
  42.      rcsedit.c       5.11
  43.      rcsfcmp.c       5.9
  44.      rcsgen.c        5.10
  45.      rcslex.c        5.11
  46.      rcsmap.c        5.2
  47.      rcsutil.c       5.10
  48.  
  49.    You can use the `tag' command to give a symbolic name to a certain
  50. revision of a file.  You can use the `-v' flag to the `status' command
  51. to see all tags that a file has, and which revision numbers they
  52. represent.  Tag names must start with an uppercase or lowercase letter
  53. and can contain uppercase and lowercase letters, digits, `-', and `_'.
  54. The two tag names `BASE' and `HEAD' are reserved for use by CVS.  It is
  55. expected that future names which are special to CVS will be specially
  56. named, for example by starting with `.', rather than being named
  57. analogously to `BASE' and `HEAD', to avoid conflicts with actual tag
  58. names.
  59.  
  60.    You'll want to choose some convention for naming tags, based on
  61. information such as the name of the program and the version number of
  62. the release.  For example, one might take the name of the program,
  63. immediately followed by the version number with `.' changed to `-', so
  64. that CVS 1.9 would be tagged with the name `cvs1-9'.  If you choose a
  65. consistent convention, then you won't constantly be guessing whether a
  66. tag is `cvs-1-9' or `cvs1_9' or what.  You might even want to consider
  67. enforcing your convention in the taginfo file (*note user-defined
  68. logging::).
  69.  
  70.    The following example shows how you can add a tag to a file.  The
  71. commands must be issued inside your working directory.  That is, you
  72. should issue the command in the directory where `backend.c' resides.
  73.  
  74.      $ cvs tag rel-0-4 backend.c
  75.      T backend.c
  76.      $ cvs status -v backend.c
  77.      ===================================================================
  78.      File: backend.c         Status: Up-to-date
  79.      
  80.          Version:            1.4     Tue Dec  1 14:39:01 1992
  81.          RCS Version:        1.4     /u/cvsroot/yoyodyne/tc/backend.c,v
  82.          Sticky Tag:         (none)
  83.          Sticky Date:        (none)
  84.          Sticky Options:     (none)
  85.      
  86.          Existing Tags:
  87.              rel-0-4                     (revision: 1.4)
  88.  
  89.    For a complete summary of the syntax of `cvs tag', including the
  90. various options, see *Note Invoking CVS::.
  91.  
  92.    There is seldom reason to tag a file in isolation.  A more common
  93. use is to tag all the files that constitute a module with the same tag
  94. at strategic points in the development life-cycle, such as when a
  95. release is made.
  96.  
  97.      $ cvs tag rel-1-0 .
  98.      cvs tag: Tagging .
  99.      T Makefile
  100.      T backend.c
  101.      T driver.c
  102.      T frontend.c
  103.      T parser.c
  104.  
  105.    (When you give CVS a directory as argument, it generally applies the
  106. operation to all the files in that directory, and (recursively), to any
  107. subdirectories that it may contain.  *Note Recursive behavior::.)
  108.  
  109.    The `checkout' command has a flag, `-r', that lets you check out a
  110. certain revision of a module.  This flag makes it easy to retrieve the
  111. sources that make up release 1.0 of the module `tc' at any time in the
  112. future:
  113.  
  114.      $ cvs checkout -r rel-1-0 tc
  115.  
  116. This is useful, for instance, if someone claims that there is a bug in
  117. that release, but you cannot find the bug in the current working copy.
  118.  
  119.    You can also check out a module as it was at any given date.  *Note
  120. checkout options::.  When specifying `-r' to any of these commands, you
  121. will need beware of sticky tags; see *Note Sticky tags::.
  122.  
  123.    When you tag more than one file with the same tag you can think
  124. about the tag as "a curve drawn through a matrix of filename vs.
  125. revision number."  Say we have 5 files with the following revisions:
  126.  
  127.              file1   file2   file3   file4   file5
  128.      
  129.              1.1     1.1     1.1     1.1  /--1.1*      <-*-  TAG
  130.              1.2*-   1.2     1.2    -1.2*-
  131.              1.3  \- 1.3*-   1.3   / 1.3
  132.              1.4          \  1.4  /  1.4
  133.                            \-1.5*-   1.5
  134.                              1.6
  135.  
  136.    At some time in the past, the `*' versions were tagged.  You can
  137. think of the tag as a handle attached to the curve drawn through the
  138. tagged revisions.  When you pull on the handle, you get all the tagged
  139. revisions.  Another way to look at it is that you "sight" through a set
  140. of revisions that is "flat" along the tagged revisions, like this:
  141.  
  142.              file1   file2   file3   file4   file5
  143.      
  144.                              1.1
  145.                              1.2
  146.                      1.1     1.3                       _
  147.              1.1     1.2     1.4     1.1              /
  148.              1.2*----1.3*----1.5*----1.2*----1.1     (--- <--- Look here
  149.              1.3             1.6     1.3              \_
  150.              1.4                     1.4
  151.                                      1.5
  152.  
  153. 
  154. File: cvs.info,  Node: Tagging the working directory,  Next: Tagging by date/tag,  Prev: Tags,  Up: Revisions
  155.  
  156. Specifying what to tag from the working directory
  157. =================================================
  158.  
  159.    The example in the previous section demonstrates one of the most
  160. common ways to choose which revisions to tag.  Namely, running the `cvs
  161. tag' command without arguments causes CVS to select the revisions which
  162. are checked out in the current working directory.  For example, if the
  163. copy of `backend.c' in working directory was checked out from revision
  164. 1.4, then CVS will tag revision 1.4.  Note that the tag is applied
  165. immediately to revision 1.4 in the repository; tagging is not like
  166. modifying a file, or other operations in which one first modifies the
  167. working directory and then runs `cvs commit' to transfer that
  168. modification to the repository.
  169.  
  170.    One potentially surprising aspect of the fact that `cvs tag'
  171. operates on the repository is that you are tagging the checked-in
  172. revisions, which may differ from locally modified files in your working
  173. directory.  If you want to avoid doing this by mistake, specify the
  174. `-c' option to `cvs tag'.  If there are any locally modified files, CVS
  175. will abort with an error before it tags any files:
  176.  
  177.      $ cvs tag -c rel-0-4
  178.      cvs tag: backend.c is locally modified
  179.      cvs [tag aborted]: correct the above errors first!
  180.  
  181. 
  182. File: cvs.info,  Node: Tagging by date/tag,  Next: Modifying tags,  Prev: Tagging the working directory,  Up: Revisions
  183.  
  184. Specifying what to tag by date or revision
  185. ==========================================
  186.  
  187.    The `cvs rtag' command tags the repository as of a certain date or
  188. time (or can be used to tag the latest revision).  `rtag' works
  189. directly on the repository contents (it requires no prior checkout and
  190. does not look for a working directory).
  191.  
  192.    The following options specify which date or revision to tag.  See
  193. *Note Common options::, for a complete description of them.
  194.  
  195. `-D DATE'
  196.      Tag the most recent revision no later than DATE.
  197.  
  198. `-f'
  199.      Only useful with the `-D DATE' or `-r TAG' flags.  If no matching
  200.      revision is found, use the most recent revision (instead of
  201.      ignoring the file).
  202.  
  203. `-r TAG'
  204.      Only tag those files that contain existing tag TAG.
  205.  
  206.    The `cvs tag' command also allows one to specify files by revision
  207. or date, using the same `-r', `-D', and `-f' options.  However, this
  208. feature is probably not what you want.  The reason is that `cvs tag'
  209. chooses which files to tag based on the files that exist in the working
  210. directory, rather than the files which existed as of the given tag/date.
  211. Therefore, you are generally better off using `cvs rtag'.  The
  212. exceptions might be cases like:
  213.  
  214.      cvs tag -r 1.4 backend.c
  215.  
  216. 
  217. File: cvs.info,  Node: Modifying tags,  Next: Tagging add/remove,  Prev: Tagging by date/tag,  Up: Revisions
  218.  
  219. Deleting, moving, and renaming tags
  220. ===================================
  221.  
  222.    Normally one does not modify tags.  They exist in order to record
  223. the history of the repository and so deleting them or changing their
  224. meaning would, generally, not be what you want.
  225.  
  226.    However, there might be cases in which one uses a tag temporarily or
  227. accidentally puts one in the wrong place.  Therefore, one might delete,
  228. move, or rename a tag.  Warning: the commands in this section are
  229. dangerous; they permanently discard historical information and it can
  230. difficult or impossible to recover from errors.  If you are a CVS
  231. administrator, you may consider restricting these commands with taginfo
  232. (*note user-defined logging::).
  233.  
  234.    To delete a tag, specify the `-d' option to either `cvs tag' or `cvs
  235. rtag'.  For example:
  236.  
  237.      cvs rtag -d rel-0-4 tc
  238.  
  239.    deletes the tag `rel-0-4' from the module `tc'.
  240.  
  241.    When we say "move" a tag, we mean to make the same name point to
  242. different revisions.  For example, the `stable' tag may currently point
  243. to revision 1.4 of `backend.c' and perhaps we want to make it point to
  244. revision 1.6.  To move a tag, specify the `-F' option to either `cvs
  245. tag' or `cvs rtag'.  For example, the task just mentioned might be
  246. accomplished as:
  247.  
  248.      cvs tag -r 1.6 -F stable backend.c
  249.  
  250.    When we say "rename" a tag, we mean to make a different name point
  251. to the same revisions as the old tag.  For example, one may have
  252. misspelled the tag name and want to correct it (hopefully before others
  253. are relying on the old spelling).  To rename a tag, first create a new
  254. tag using the `-r' option to `cvs rtag', and then delete the old name.
  255. This leaves the new tag on exactly the same files as the old tag.  For
  256. example:
  257.  
  258.      cvs rtag -r old-name-0-4 rel-0-4 tc
  259.      cvs rtag -d old-name-0-4 tc
  260.  
  261. 
  262. File: cvs.info,  Node: Tagging add/remove,  Next: Sticky tags,  Prev: Modifying tags,  Up: Revisions
  263.  
  264. Tagging and adding and removing files
  265. =====================================
  266.  
  267.    The subject of exactly how tagging interacts with adding and
  268. removing files is somewhat obscure; for the most part CVS will keep
  269. track of whether files exist or not without too much fussing.  By
  270. default, tags are applied to only files which have a revision
  271. corresponding to what is being tagged.  Files which did not exist yet,
  272. or which were already removed, simply omit the tag, and CVS knows to
  273. treat the absence of a tag as meaning that the file didn't exist as of
  274. that tag.
  275.  
  276.    However, this can lose a small amount of information.  For example,
  277. suppose a file was added and then removed.  Then, if the tag is missing
  278. for that file, there is no way to know whether the tag refers to the
  279. time before the file was added, or the time after it was removed.  If
  280. you specify the `-r' option to `cvs rtag', then CVS tags the files
  281. which have been removed, and thereby avoids this problem.  For example,
  282. one might specify `-r HEAD' to tag the head.
  283.  
  284.    On the subject of adding and removing files, the `cvs rtag' command
  285. has a `-a' option which means to clear the tag from removed files that
  286. would not otherwise be tagged.  For example, one might specify this
  287. option in conjunction with `-F' when moving a tag.  If one moved a tag
  288. without `-a', then the tag in the removed files might still refer to
  289. the old revision, rather than reflecting the fact that the file had
  290. been removed.  I don't think this is necessary if `-r' is specified, as
  291. noted above.
  292.  
  293. 
  294. File: cvs.info,  Node: Sticky tags,  Prev: Tagging add/remove,  Up: Revisions
  295.  
  296. Sticky tags
  297. ===========
  298.  
  299.    Sometimes a working copy's revision has extra data associated with
  300. it, for example it might be on a branch (*note Branching and
  301. merging::), or restricted to versions prior to a certain date by
  302. `checkout -D' or `update -D'.  Because this data persists - that is, it
  303. applies to subsequent commands in the working copy - we refer to it as
  304. "sticky".
  305.  
  306.    Most of the time, stickiness is an obscure aspect of CVS that you
  307. don't need to think about.  However, even if you don't want to use the
  308. feature, you may need to know _something_ about sticky tags (for
  309. example, how to avoid them!).
  310.  
  311.    You can use the `status' command to see if any sticky tags or dates
  312. are set:
  313.  
  314.      $ cvs status driver.c
  315.      ===================================================================
  316.      File: driver.c          Status: Up-to-date
  317.      
  318.          Version:            1.7.2.1 Sat Dec  5 19:35:03 1992
  319.          RCS Version:        1.7.2.1 /u/cvsroot/yoyodyne/tc/driver.c,v
  320.          Sticky Tag:         rel-1-0-patches (branch: 1.7.2)
  321.          Sticky Date:        (none)
  322.          Sticky Options:     (none)
  323.  
  324.    The sticky tags will remain on your working files until you delete
  325. them with `cvs update -A'.  The `-A' option retrieves the version of
  326. the file from the head of the trunk, and forgets any sticky tags,
  327. dates, or options.
  328.  
  329.    The most common use of sticky tags is to identify which branch one
  330. is working on, as described in *Note Accessing branches::.  However,
  331. non-branch sticky tags have uses as well.  For example, suppose that
  332. you want to avoid updating your working directory, to isolate yourself
  333. from possibly destabilizing changes other people are making.  You can,
  334. of course, just refrain from running `cvs update'.  But if you want to
  335. avoid updating only a portion of a larger tree, then sticky tags can
  336. help.  If you check out a certain revision (such as 1.4) it will become
  337. sticky.  Subsequent `cvs update' commands will not retrieve the latest
  338. revision until you reset the tag with `cvs update -A'.  Likewise, use
  339. of the `-D' option to `update' or `checkout' sets a "sticky date",
  340. which, similarly, causes that date to be used for future retrievals.
  341.  
  342.    People often want to retrieve an old version of a file without
  343. setting a sticky tag.  This can be done with the `-p' option to
  344. `checkout' or `update', which sends the contents of the file to
  345. standard output.  For example:
  346.      $ cvs update -p -r 1.1 file1 >file1
  347.      ===================================================================
  348.      Checking out file1
  349.      RCS:  /tmp/cvs-sanity/cvsroot/first-dir/Attic/file1,v
  350.      VERS: 1.1
  351.      ***************
  352.      $
  353.  
  354.    However, this isn't the easiest way, if you are asking how to undo a
  355. previous checkin (in this example, put `file1' back to the way it was
  356. as of revision 1.1).  In that case you are better off using the `-j'
  357. option to `update'; for further discussion see *Note Merging two
  358. revisions::.
  359.  
  360. 
  361. File: cvs.info,  Node: Branching and merging,  Next: Recursive behavior,  Prev: Revisions,  Up: Top
  362.  
  363. Branching and merging
  364. *********************
  365.  
  366.    CVS allows you to isolate changes onto a separate line of
  367. development, known as a "branch".  When you change files on a branch,
  368. those changes do not appear on the main trunk or other branches.
  369.  
  370.    Later you can move changes from one branch to another branch (or the
  371. main trunk) by "merging".  Merging involves first running `cvs update
  372. -j', to merge the changes into the working directory.  You can then
  373. commit that revision, and thus effectively copy the changes onto
  374. another branch.
  375.  
  376. * Menu:
  377.  
  378. * Branches motivation::         What branches are good for
  379. * Creating a branch::           Creating a branch
  380. * Accessing branches::          Checking out and updating branches
  381. * Branches and revisions::      Branches are reflected in revision numbers
  382. * Magic branch numbers::        Magic branch numbers
  383. * Merging a branch::            Merging an entire branch
  384. * Merging more than once::      Merging from a branch several times
  385. * Merging two revisions::       Merging differences between two revisions
  386. * Merging adds and removals::   What if files are added or removed?
  387. * Merging and keywords::        Avoiding conflicts due to keyword substitution
  388.  
  389. 
  390. File: cvs.info,  Node: Branches motivation,  Next: Creating a branch,  Up: Branching and merging
  391.  
  392. What branches are good for
  393. ==========================
  394.  
  395.    Suppose that release 1.0 of tc has been made.  You are continuing to
  396. develop tc, planning to create release 1.1 in a couple of months.
  397. After a while your customers start to complain about a fatal bug.  You
  398. check out release 1.0 (*note Tags::) and find the bug (which turns out
  399. to have a trivial fix).  However, the current revision of the sources
  400. are in a state of flux and are not expected to be stable for at least
  401. another month.  There is no way to make a bugfix release based on the
  402. newest sources.
  403.  
  404.    The thing to do in a situation like this is to create a "branch" on
  405. the revision trees for all the files that make up release 1.0 of tc.
  406. You can then make modifications to the branch without disturbing the
  407. main trunk.  When the modifications are finished you can elect to
  408. either incorporate them on the main trunk, or leave them on the branch.
  409.  
  410. 
  411. File: cvs.info,  Node: Creating a branch,  Next: Accessing branches,  Prev: Branches motivation,  Up: Branching and merging
  412.  
  413. Creating a branch
  414. =================
  415.  
  416.    You can create a branch with `tag -b'; for example, assuming you're
  417. in a working copy:
  418.  
  419.      $ cvs tag -b rel-1-0-patches
  420.  
  421.    This splits off a branch based on the current revisions in the
  422. working copy, assigning that branch the name `rel-1-0-patches'.
  423.  
  424.    It is important to understand that branches get created in the
  425. repository, not in the working copy.  Creating a branch based on
  426. current revisions, as the above example does, will _not_ automatically
  427. switch the working copy to be on the new branch.  For information on how
  428. to do that, see *Note Accessing branches::.
  429.  
  430.    You can also create a branch without reference to any working copy,
  431. by using `rtag':
  432.  
  433.      $ cvs rtag -b -r rel-1-0 rel-1-0-patches tc
  434.  
  435.    `-r rel-1-0' says that this branch should be rooted at the revision
  436. that corresponds to the tag `rel-1-0'.  It need not be the most recent
  437. revision - it's often useful to split a branch off an old revision (for
  438. example, when fixing a bug in a past release otherwise known to be
  439. stable).
  440.  
  441.    As with `tag', the `-b' flag tells `rtag' to create a branch (rather
  442. than just a symbolic revision name).  Note that the numeric revision
  443. number that matches `rel-1-0' will probably be different from file to
  444. file.
  445.  
  446.    So, the full effect of the command is to create a new branch - named
  447. `rel-1-0-patches' - in module `tc', rooted in the revision tree at the
  448. point tagged by `rel-1-0'.
  449.  
  450. 
  451. File: cvs.info,  Node: Accessing branches,  Next: Branches and revisions,  Prev: Creating a branch,  Up: Branching and merging
  452.  
  453. Accessing branches
  454. ==================
  455.  
  456.    You can retrieve a branch in one of two ways: by checking it out
  457. fresh from the repository, or by switching an existing working copy
  458. over to the branch.
  459.  
  460.    To check out a branch from the repository, invoke `checkout' with
  461. the `-r' flag, followed by the tag name of the branch (*note Creating a
  462. branch::):
  463.  
  464.      $ cvs checkout -r rel-1-0-patches tc
  465.  
  466.    Or, if you already have a working copy, you can switch it to a given
  467. branch with `update -r':
  468.  
  469.      $ cvs update -r rel-1-0-patches tc
  470.  
  471.    or equivalently:
  472.  
  473.      $ cd tc
  474.      $ cvs update -r rel-1-0-patches
  475.  
  476.    It does not matter if the working copy was originally on the main
  477. trunk or on some other branch - the above command will switch it to the
  478. named branch.  And similarly to a regular `update' command, `update -r'
  479. merges any changes you have made, notifying you of conflicts where they
  480. occur.
  481.  
  482.    Once you have a working copy tied to a particular branch, it remains
  483. there until you tell it otherwise.  This means that changes checked in
  484. from the working copy will add new revisions on that branch, while
  485. leaving the main trunk and other branches unaffected.
  486.  
  487.    To find out what branch a working copy is on, you can use the
  488. `status' command.  In its output, look for the field named `Sticky tag'
  489. (*note Sticky tags::) - that's CVS's way of telling you the branch, if
  490. any, of the current working files:
  491.  
  492.      $ cvs status -v driver.c backend.c
  493.      ===================================================================
  494.      File: driver.c          Status: Up-to-date
  495.      
  496.          Version:            1.7     Sat Dec  5 18:25:54 1992
  497.          RCS Version:        1.7     /u/cvsroot/yoyodyne/tc/driver.c,v
  498.          Sticky Tag:         rel-1-0-patches (branch: 1.7.2)
  499.          Sticky Date:        (none)
  500.          Sticky Options:     (none)
  501.      
  502.          Existing Tags:
  503.              rel-1-0-patches             (branch: 1.7.2)
  504.              rel-1-0                     (revision: 1.7)
  505.      
  506.      ===================================================================
  507.      File: backend.c         Status: Up-to-date
  508.      
  509.          Version:            1.4     Tue Dec  1 14:39:01 1992
  510.          RCS Version:        1.4     /u/cvsroot/yoyodyne/tc/backend.c,v
  511.          Sticky Tag:         rel-1-0-patches (branch: 1.4.2)
  512.          Sticky Date:        (none)
  513.          Sticky Options:     (none)
  514.      
  515.          Existing Tags:
  516.              rel-1-0-patches             (branch: 1.4.2)
  517.              rel-1-0                     (revision: 1.4)
  518.              rel-0-4                     (revision: 1.4)
  519.  
  520.    Don't be confused by the fact that the branch numbers for each file
  521. are different (`1.7.2' and `1.4.2' respectively).  The branch tag is the
  522. same, `rel-1-0-patches', and the files are indeed on the same branch.
  523. The numbers simply reflect the point in each file's revision history at
  524. which the branch was made.  In the above example, one can deduce that
  525. `driver.c' had been through more changes than `backend.c' before this
  526. branch was created.
  527.  
  528.    See *Note Branches and revisions:: for details about how branch
  529. numbers are constructed.
  530.  
  531. 
  532. File: cvs.info,  Node: Branches and revisions,  Next: Magic branch numbers,  Prev: Accessing branches,  Up: Branching and merging
  533.  
  534. Branches and revisions
  535. ======================
  536.  
  537.    Ordinarily, a file's revision history is a linear series of
  538. increments (*note Revision numbers::):
  539.  
  540.             +-----+    +-----+    +-----+    +-----+    +-----+
  541.             ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !
  542.             +-----+    +-----+    +-----+    +-----+    +-----+
  543.  
  544.    However, CVS is not limited to linear development.  The "revision
  545. tree" can be split into "branches", where each branch is a
  546. self-maintained line of development.  Changes made on one branch can
  547. easily be moved back to the main trunk.
  548.  
  549.    Each branch has a "branch number", consisting of an odd number of
  550. period-separated decimal integers.  The branch number is created by
  551. appending an integer to the revision number where the corresponding
  552. branch forked off.  Having branch numbers allows more than one branch
  553. to be forked off from a certain revision.
  554.  
  555.    All revisions on a branch have revision numbers formed by appending
  556. an ordinal number to the branch number.  The following figure
  557. illustrates branching with an example.
  558.  
  559.                                                            +-------------+
  560.                                 Branch 1.2.2.3.2 ->        ! 1.2.2.3.2.1 !
  561.                                                          / +-------------+
  562.                                                         /
  563.                                                        /
  564.                       +---------+    +---------+    +---------+
  565.      Branch 1.2.2 -> _! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 !
  566.                     / +---------+    +---------+    +---------+
  567.                    /
  568.                   /
  569.      +-----+    +-----+    +-----+    +-----+    +-----+
  570.      ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !  <- The main trunk
  571.      +-----+    +-----+    +-----+    +-----+    +-----+
  572.                      !
  573.                      !
  574.                      !   +---------+    +---------+    +---------+
  575.      Branch 1.2.4 -> +---! 1.2.4.1 !----! 1.2.4.2 !----! 1.2.4.3 !
  576.                          +---------+    +---------+    +---------+
  577.  
  578.    The exact details of how the branch number is constructed is not
  579. something you normally need to be concerned about, but here is how it
  580. works: When CVS creates a branch number it picks the first unused even
  581. integer, starting with 2.  So when you want to create a branch from
  582. revision 6.4 it will be numbered 6.4.2.  All branch numbers ending in a
  583. zero (such as 6.4.0) are used internally by CVS (*note Magic branch
  584. numbers::).  The branch 1.1.1 has a special meaning.  *Note Tracking
  585. sources::.
  586.  
  587. 
  588. File: cvs.info,  Node: Magic branch numbers,  Next: Merging a branch,  Prev: Branches and revisions,  Up: Branching and merging
  589.  
  590. Magic branch numbers
  591. ====================
  592.  
  593.    This section describes a CVS feature called "magic branches".  For
  594. most purposes, you need not worry about magic branches; CVS handles
  595. them for you.  However, they are visible to you in certain
  596. circumstances, so it may be useful to have some idea of how it works.
  597.  
  598.    Externally, branch numbers consist of an odd number of dot-separated
  599. decimal integers.  *Note Revision numbers::.  That is not the whole
  600. truth, however.  For efficiency reasons CVS sometimes inserts an extra 0
  601. in the second rightmost position (1.2.4 becomes 1.2.0.4, 8.9.10.11.12
  602. becomes 8.9.10.11.0.12 and so on).
  603.  
  604.    CVS does a pretty good job at hiding these so called magic branches,
  605. but in a few places the hiding is incomplete:
  606.  
  607.    * The magic branch number appears in the output from `cvs log'.
  608.  
  609.    * You cannot specify a symbolic branch name to `cvs admin'.
  610.  
  611.  
  612.    You can use the `admin' command to reassign a symbolic name to a
  613. branch the way RCS expects it to be.  If `R4patches' is assigned to the
  614. branch 1.4.2 (magic branch number 1.4.0.2) in file `numbers.c' you can
  615. do this:
  616.  
  617.      $ cvs admin -NR4patches:1.4.2 numbers.c
  618.  
  619.    It only works if at least one revision is already committed on the
  620. branch.  Be very careful so that you do not assign the tag to the wrong
  621. number.  (There is no way to see how the tag was assigned yesterday).
  622.  
  623. 
  624. File: cvs.info,  Node: Merging a branch,  Next: Merging more than once,  Prev: Magic branch numbers,  Up: Branching and merging
  625.  
  626. Merging an entire branch
  627. ========================
  628.  
  629.    You can merge changes made on a branch into your working copy by
  630. giving the `-j BRANCHNAME' flag to the `update' subcommand.  With one
  631. `-j BRANCHNAME' option it merges the changes made between the point
  632. where the branch forked and newest revision on that branch (into your
  633. working copy).
  634.  
  635.    The `-j' stands for "join".
  636.  
  637.    Consider this revision tree:
  638.  
  639.      +-----+    +-----+    +-----+    +-----+
  640.      ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !      <- The main trunk
  641.      +-----+    +-----+    +-----+    +-----+
  642.                      !
  643.                      !
  644.                      !   +---------+    +---------+
  645.      Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !
  646.                          +---------+    +---------+
  647.  
  648. The branch 1.2.2 has been given the tag (symbolic name) `R1fix'.  The
  649. following example assumes that the module `mod' contains only one file,
  650. `m.c'.
  651.  
  652.      $ cvs checkout mod               # Retrieve the latest revision, 1.4
  653.      
  654.      $ cvs update -j R1fix m.c        # Merge all changes made on the branch,
  655.                                       # i.e. the changes between revision 1.2
  656.                                       # and 1.2.2.2, into your working copy
  657.                                       # of the file.
  658.      
  659.      $ cvs commit -m "Included R1fix" # Create revision 1.5.
  660.  
  661.    A conflict can result from a merge operation.  If that happens, you
  662. should resolve it before committing the new revision.  *Note Conflicts
  663. example::.
  664.  
  665.    If your source files contain keywords (*note Keyword substitution::),
  666. you might be getting more conflicts than strictly necessary.  See *Note
  667. Merging and keywords::, for information on how to avoid this.
  668.  
  669.    The `checkout' command also supports the `-j BRANCHNAME' flag.  The
  670. same effect as above could be achieved with this:
  671.  
  672.      $ cvs checkout -j R1fix mod
  673.      $ cvs commit -m "Included R1fix"
  674.  
  675.    It should be noted that `update -j TAGNAME' will also work but may
  676. not produce the desired result.  *Note Merging adds and removals::, for
  677. more.
  678.  
  679. 
  680. File: cvs.info,  Node: Merging more than once,  Next: Merging two revisions,  Prev: Merging a branch,  Up: Branching and merging
  681.  
  682. Merging from a branch several times
  683. ===================================
  684.  
  685.    Continuing our example, the revision tree now looks like this:
  686.  
  687.      +-----+    +-----+    +-----+    +-----+    +-----+
  688.      ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !   <- The main trunk
  689.      +-----+    +-----+    +-----+    +-----+    +-----+
  690.                      !                           *
  691.                      !                          *
  692.                      !   +---------+    +---------+
  693.      Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !
  694.                          +---------+    +---------+
  695.  
  696.    where the starred line represents the merge from the `R1fix' branch
  697. to the main trunk, as just discussed.
  698.  
  699.    Now suppose that development continues on the `R1fix' branch:
  700.  
  701.      +-----+    +-----+    +-----+    +-----+    +-----+
  702.      ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !   <- The main trunk
  703.      +-----+    +-----+    +-----+    +-----+    +-----+
  704.                      !                           *
  705.                      !                          *
  706.                      !   +---------+    +---------+    +---------+
  707.      Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 !
  708.                          +---------+    +---------+    +---------+
  709.  
  710.    and then you want to merge those new changes onto the main trunk.
  711. If you just use the `cvs update -j R1fix m.c' command again, CVS will
  712. attempt to merge again the changes which you have already merged, which
  713. can have undesirable side effects.
  714.  
  715.    So instead you need to specify that you only want to merge the
  716. changes on the branch which have not yet been merged into the trunk.
  717. To do that you specify two `-j' options, and CVS merges the changes from
  718. the first revision to the second revision.  For example, in this case
  719. the simplest way would be
  720.  
  721.      cvs update -j 1.2.2.2 -j R1fix m.c    # Merge changes from 1.2.2.2 to the
  722.                                            # head of the R1fix branch
  723.  
  724.    The problem with this is that you need to specify the 1.2.2.2
  725. revision manually.  A slightly better approach might be to use the date
  726. the last merge was done:
  727.  
  728.      cvs update -j R1fix:yesterday -j R1fix m.c
  729.  
  730.    Better yet, tag the R1fix branch after every merge into the trunk,
  731. and then use that tag for subsequent merges:
  732.  
  733.      cvs update -j merged_from_R1fix_to_trunk -j R1fix m.c
  734.  
  735. 
  736. File: cvs.info,  Node: Merging two revisions,  Next: Merging adds and removals,  Prev: Merging more than once,  Up: Branching and merging
  737.  
  738. Merging differences between any two revisions
  739. =============================================
  740.  
  741.    With two `-j REVISION' flags, the `update' (and `checkout') command
  742. can merge the differences between any two revisions into your working
  743. file.
  744.  
  745.      $ cvs update -j 1.5 -j 1.3 backend.c
  746.  
  747. will undo all changes made between revision 1.3 and 1.5.  Note the
  748. order of the revisions!
  749.  
  750.    If you try to use this option when operating on multiple files,
  751. remember that the numeric revisions will probably be very different
  752. between the various files.  You almost always use symbolic tags rather
  753. than revision numbers when operating on multiple files.
  754.  
  755.    Specifying two `-j' options can also undo file removals or
  756. additions.  For example, suppose you have a file named `file1' which
  757. existed as revision 1.1, and you then removed it (thus adding a dead
  758. revision 1.2).  Now suppose you want to add it again, with the same
  759. contents it had previously.  Here is how to do it:
  760.  
  761.      $ cvs update -j 1.2 -j 1.1 file1
  762.      U file1
  763.      $ cvs commit -m test
  764.      Checking in file1;
  765.      /tmp/cvs-sanity/cvsroot/first-dir/file1,v  <--  file1
  766.      new revision: 1.3; previous revision: 1.2
  767.      done
  768.      $
  769.  
  770. 
  771. File: cvs.info,  Node: Merging adds and removals,  Next: Merging and keywords,  Prev: Merging two revisions,  Up: Branching and merging
  772.  
  773. Merging can add or remove files
  774. ===============================
  775.  
  776.    If the changes which you are merging involve removing or adding some
  777. files, `update -j' will reflect such additions or removals.
  778.  
  779.    For example:
  780.      cvs update -A
  781.      touch a b c
  782.      cvs add a b c ; cvs ci -m "added" a b c
  783.      cvs tag -b branchtag
  784.      cvs update -r branchtag
  785.      touch d ; cvs add d
  786.      rm a ; cvs rm a
  787.      cvs ci -m "added d, removed a"
  788.      cvs update -A
  789.      cvs update -jbranchtag
  790.  
  791.    After these commands are executed and a `cvs commit' is done, file
  792. `a' will be removed and file `d' added in the main branch.
  793.  
  794.    Note that using a single static tag (`-j TAGNAME') rather than a
  795. dynamic tag (`-j BRANCHNAME') to merge changes from a branch will
  796. usually not remove files which were removed on the branch since CVS
  797. does not automatically add static tags to dead revisions.  The
  798. exception to this rule occurs when a static tag has been attached to a
  799. dead revision manually.  Use the branch tag to merge all changes from
  800. the branch or use two static tags as merge endpoints to be sure that
  801. all intended changes are propogated in the merge.
  802.  
  803. 
  804. File: cvs.info,  Node: Merging and keywords,  Prev: Merging adds and removals,  Up: Branching and merging
  805.  
  806. Merging and keywords
  807. ====================
  808.  
  809.    If you merge files containing keywords (*note Keyword
  810. substitution::), you will normally get numerous conflicts during the
  811. merge, because the keywords are expanded differently in the revisions
  812. which you are merging.
  813.  
  814.    Therefore, you will often want to specify the `-kk' (*note
  815. Substitution modes::) switch to the merge command line.  By
  816. substituting just the name of the keyword, not the expanded value of
  817. that keyword, this option ensures that the revisions which you are
  818. merging will be the same as each other, and avoid spurious conflicts.
  819.  
  820.    For example, suppose you have a file like this:
  821.  
  822.             +---------+
  823.            _! 1.1.2.1 !   <-  br1
  824.           / +---------+
  825.          /
  826.         /
  827.      +-----+    +-----+
  828.      ! 1.1 !----! 1.2 !
  829.      +-----+    +-----+
  830.  
  831.    and your working directory is currently on the trunk (revision 1.2).
  832. Then you might get the following results from a merge:
  833.  
  834.      $ cat file1
  835.      key $Revision: 1.2 $
  836.      . . .
  837.      $ cvs update -j br1
  838.      U file1
  839.      RCS file: /cvsroot/first-dir/file1,v
  840.      retrieving revision 1.1
  841.      retrieving revision 1.1.2.1
  842.      Merging differences between 1.1 and 1.1.2.1 into file1
  843.      rcsmerge: warning: conflicts during merge
  844.      $ cat file1
  845.      <<<<<<< file1
  846.      key $Revision: 1.2 $
  847.      =======
  848.      key $Revision: 1.1.2.1 $
  849.      >>>>>>> 1.1.2.1
  850.      . . .
  851.  
  852.    What happened was that the merge tried to merge the differences
  853. between 1.1 and 1.1.2.1 into your working directory.  So, since the
  854. keyword changed from `Revision: 1.1' to `Revision: 1.1.2.1', CVS tried
  855. to merge that change into your working directory, which conflicted with
  856. the fact that your working directory had contained `Revision: 1.2'.
  857.  
  858.    Here is what happens if you had used `-kk':
  859.  
  860.      $ cat file1
  861.      key $Revision: 1.2 $
  862.      . . .
  863.      $ cvs update -kk -j br1
  864.      U file1
  865.      RCS file: /cvsroot/first-dir/file1,v
  866.      retrieving revision 1.1
  867.      retrieving revision 1.1.2.1
  868.      Merging differences between 1.1 and 1.1.2.1 into file1
  869.      $ cat file1
  870.      key $Revision$
  871.      . . .
  872.  
  873.    What is going on here is that revision 1.1 and 1.1.2.1 both expand
  874. as plain `Revision', and therefore merging the changes between them
  875. into the working directory need not change anything.  Therefore, there
  876. is no conflict.
  877.  
  878.    There is, however, one major caveat with using `-kk' on merges.
  879. Namely, it overrides whatever keyword expansion mode CVS would normally
  880. have used.  In particular, this is a problem if the mode had been `-kb'
  881. for a binary file.  Therefore, if your repository contains binary
  882. files, you will need to deal with the conflicts rather than using `-kk'.
  883.  
  884. 
  885. File: cvs.info,  Node: Recursive behavior,  Next: Adding and removing,  Prev: Branching and merging,  Up: Top
  886.  
  887. Recursive behavior
  888. ******************
  889.  
  890.    Almost all of the subcommands of CVS work recursively when you
  891. specify a directory as an argument.  For instance, consider this
  892. directory structure:
  893.  
  894.            `$HOME'
  895.              |
  896.              +--tc
  897.              |   |
  898.                  +--CVS
  899.                  |      (internal CVS files)
  900.                  +--Makefile
  901.                  +--backend.c
  902.                  +--driver.c
  903.                  +--frontend.c
  904.                  +--parser.c
  905.                  +--man
  906.                  |    |
  907.                  |    +--CVS
  908.                  |    |  (internal CVS files)
  909.                  |    +--tc.1
  910.                  |
  911.                  +--testing
  912.                       |
  913.                       +--CVS
  914.                       |  (internal CVS files)
  915.                       +--testpgm.t
  916.                       +--test2.t
  917.  
  918. If `tc' is the current working directory, the following is true:
  919.  
  920.    * `cvs update testing' is equivalent to
  921.  
  922.           cvs update testing/testpgm.t testing/test2.t
  923.  
  924.    * `cvs update testing man' updates all files in the subdirectories
  925.  
  926.    * `cvs update .' or just `cvs update' updates all files in the `tc'
  927.      directory
  928.  
  929.    If no arguments are given to `update' it will update all files in
  930. the current working directory and all its subdirectories.  In other
  931. words, `.' is a default argument to `update'.  This is also true for
  932. most of the CVS subcommands, not only the `update' command.
  933.  
  934.    The recursive behavior of the CVS subcommands can be turned off with
  935. the `-l' option.  Conversely, the `-R' option can be used to force
  936. recursion if `-l' is specified in `~/.cvsrc' (*note ~/.cvsrc::).
  937.  
  938.      $ cvs update -l         # Don't update files in subdirectories
  939.  
  940. 
  941. File: cvs.info,  Node: Adding and removing,  Next: History browsing,  Prev: Recursive behavior,  Up: Top
  942.  
  943. Adding, removing, and renaming files and directories
  944. ****************************************************
  945.  
  946.    In the course of a project, one will often add new files.  Likewise
  947. with removing or renaming, or with directories.  The general concept to
  948. keep in mind in all these cases is that instead of making an
  949. irreversible change you want CVS to record the fact that a change has
  950. taken place, just as with modifying an existing file.  The exact
  951. mechanisms to do this in CVS vary depending on the situation.
  952.  
  953. * Menu:
  954.  
  955. * Adding files::                Adding files
  956. * Removing files::              Removing files
  957. * Removing directories::        Removing directories
  958. * Moving files::                Moving and renaming files
  959. * Moving directories::          Moving and renaming directories
  960.  
  961. 
  962. File: cvs.info,  Node: Adding files,  Next: Removing files,  Up: Adding and removing
  963.  
  964. Adding files to a directory
  965. ===========================
  966.  
  967.    To add a new file to a directory, follow these steps.
  968.  
  969.    * You must have a working copy of the directory.  *Note Getting the
  970.      source::.
  971.  
  972.    * Create the new file inside your working copy of the directory.
  973.  
  974.    * Use `cvs add FILENAME' to tell CVS that you want to version
  975.      control the file.  If the file contains binary data, specify `-kb'
  976.      (*note Binary files::).
  977.  
  978.    * Use `cvs commit FILENAME' to actually check in the file into the
  979.      repository.  Other developers cannot see the file until you
  980.      perform this step.
  981.  
  982.    You can also use the `add' command to add a new directory.
  983.  
  984.    Unlike most other commands, the `add' command is not recursive.  You
  985. cannot even type `cvs add foo/bar'!  Instead, you have to
  986.  
  987.      $ cd foo
  988.      $ cvs add bar
  989.  
  990.  - Command: cvs add [`-k' kflag] [`-m' message] files ...
  991.      Schedule FILES to be added to the repository.  The files or
  992.      directories specified with `add' must already exist in the current
  993.      directory.  To add a whole new directory hierarchy to the source
  994.      repository (for example, files received from a third-party
  995.      vendor), use the `import' command instead.  *Note import::.
  996.  
  997.      The added files are not placed in the source repository until you
  998.      use `commit' to make the change permanent.  Doing an `add' on a
  999.      file that was removed with the `remove' command will undo the
  1000.      effect of the `remove', unless a `commit' command intervened.
  1001.      *Note Removing files::, for an example.
  1002.  
  1003.      The `-k' option specifies the default way that this file will be
  1004.      checked out; for more information see *Note Substitution modes::.
  1005.  
  1006.      The `-m' option specifies a description for the file.  This
  1007.      description appears in the history log (if it is enabled, *note
  1008.      history file::).  It will also be saved in the version history
  1009.      inside the repository when the file is committed.  The `log'
  1010.      command displays this description.  The description can be changed
  1011.      using `admin -t'.  *Note admin::.  If you omit the `-m
  1012.      DESCRIPTION' flag, an empty string will be used.  You will not be
  1013.      prompted for a description.
  1014.  
  1015.    For example, the following commands add the file `backend.c' to the
  1016. repository:
  1017.  
  1018.      $ cvs add backend.c
  1019.      $ cvs commit -m "Early version. Not yet compilable." backend.c
  1020.  
  1021.    When you add a file it is added only on the branch which you are
  1022. working on (*note Branching and merging::).  You can later merge the
  1023. additions to another branch if you want (*note Merging adds and
  1024. removals::).
  1025.  
  1026. 
  1027. File: cvs.info,  Node: Removing files,  Next: Removing directories,  Prev: Adding files,  Up: Adding and removing
  1028.  
  1029. Removing files
  1030. ==============
  1031.  
  1032.    Directories change.  New files are added, and old files disappear.
  1033. Still, you want to be able to retrieve an exact copy of old releases.
  1034.  
  1035.    Here is what you can do to remove a file, but remain able to
  1036. retrieve old revisions:
  1037.  
  1038.    * Make sure that you have not made any uncommitted modifications to
  1039.      the file.  *Note Viewing differences::, for one way to do that.
  1040.      You can also use the `status' or `update' command.  If you remove
  1041.      the file without committing your changes, you will of course not
  1042.      be able to retrieve the file as it was immediately before you
  1043.      deleted it.
  1044.  
  1045.    * Remove the file from your working copy of the directory.  You can
  1046.      for instance use `rm'.
  1047.  
  1048.    * Use `cvs remove FILENAME' to tell CVS that you really want to
  1049.      delete the file.
  1050.  
  1051.    * Use `cvs commit FILENAME' to actually perform the removal of the
  1052.      file from the repository.
  1053.  
  1054.    When you commit the removal of the file, CVS records the fact that
  1055. the file no longer exists.  It is possible for a file to exist on only
  1056. some branches and not on others, or to re-add another file with the same
  1057. name later.  CVS will correctly create or not create the file, based on
  1058. the `-r' and `-D' options specified to `checkout' or `update'.
  1059.  
  1060.  - Command: cvs remove [options] files ...
  1061.      Schedule file(s) to be removed from the repository (files which
  1062.      have not already been removed from the working directory are not
  1063.      processed).  This command does not actually remove the file from
  1064.      the repository until you commit the removal.  For a full list of
  1065.      options, see *Note Invoking CVS::.
  1066.  
  1067.    Here is an example of removing several files:
  1068.  
  1069.      $ cd test
  1070.      $ rm *.c
  1071.      $ cvs remove
  1072.      cvs remove: Removing .
  1073.      cvs remove: scheduling a.c for removal
  1074.      cvs remove: scheduling b.c for removal
  1075.      cvs remove: use 'cvs commit' to remove these files permanently
  1076.      $ cvs ci -m "Removed unneeded files"
  1077.      cvs commit: Examining .
  1078.      cvs commit: Committing .
  1079.  
  1080.    As a convenience you can remove the file and `cvs remove' it in one
  1081. step, by specifying the `-f' option.  For example, the above example
  1082. could also be done like this:
  1083.  
  1084.      $ cd test
  1085.      $ cvs remove -f *.c
  1086.      cvs remove: scheduling a.c for removal
  1087.      cvs remove: scheduling b.c for removal
  1088.      cvs remove: use 'cvs commit' to remove these files permanently
  1089.      $ cvs ci -m "Removed unneeded files"
  1090.      cvs commit: Examining .
  1091.      cvs commit: Committing .
  1092.  
  1093.    If you execute `remove' for a file, and then change your mind before
  1094. you commit, you can undo the `remove' with an `add' command.
  1095.  
  1096.      $ ls
  1097.      CVS   ja.h  oj.c
  1098.      $ rm oj.c
  1099.      $ cvs remove oj.c
  1100.      cvs remove: scheduling oj.c for removal
  1101.      cvs remove: use 'cvs commit' to remove this file permanently
  1102.      $ cvs add oj.c
  1103.      U oj.c
  1104.      cvs add: oj.c, version 1.1.1.1, resurrected
  1105.  
  1106.    If you realize your mistake before you run the `remove' command you
  1107. can use `update' to resurrect the file:
  1108.  
  1109.      $ rm oj.c
  1110.      $ cvs update oj.c
  1111.      cvs update: warning: oj.c was lost
  1112.      U oj.c
  1113.  
  1114.    When you remove a file it is removed only on the branch which you
  1115. are working on (*note Branching and merging::).  You can later merge
  1116. the removals to another branch if you want (*note Merging adds and
  1117. removals::).
  1118.  
  1119. 
  1120. File: cvs.info,  Node: Removing directories,  Next: Moving files,  Prev: Removing files,  Up: Adding and removing
  1121.  
  1122. Removing directories
  1123. ====================
  1124.  
  1125.    In concept removing directories is somewhat similar to removing
  1126. files--you want the directory to not exist in your current working
  1127. directories, but you also want to be able to retrieve old releases in
  1128. which the directory existed.
  1129.  
  1130.    The way that you remove a directory is to remove all the files in
  1131. it.  You don't remove the directory itself; there is no way to do that.
  1132. Instead you specify the `-P' option to `cvs update' or `cvs checkout',
  1133. which will cause CVS to remove empty directories from working
  1134. directories.  (Note that `cvs export' always removes empty directories.)
  1135. Probably the best way to do this is to always specify `-P'; if you want
  1136. an empty directory then put a dummy file (for example `.keepme') in it
  1137. to prevent `-P' from removing it.
  1138.  
  1139.    Note that `-P' is implied by the `-r' or `-D' options of `checkout'.
  1140. This way CVS will be able to correctly create the directory or not
  1141. depending on whether the particular version you are checking out
  1142. contains any files in that directory.
  1143.  
  1144. 
  1145. File: cvs.info,  Node: Moving files,  Next: Moving directories,  Prev: Removing directories,  Up: Adding and removing
  1146.  
  1147. Moving and renaming files
  1148. =========================
  1149.  
  1150.    Moving files to a different directory or renaming them is not
  1151. difficult, but some of the ways in which this works may be non-obvious.
  1152. (Moving or renaming a directory is even harder.  *Note Moving
  1153. directories::.).
  1154.  
  1155.    The examples below assume that the file OLD is renamed to NEW.
  1156.  
  1157. * Menu:
  1158.  
  1159. * Outside::                     The normal way to Rename
  1160. * Inside::                      A tricky, alternative way
  1161. * Rename by copying::           Another tricky, alternative way
  1162.  
  1163. 
  1164. File: cvs.info,  Node: Outside,  Next: Inside,  Up: Moving files
  1165.  
  1166. The Normal way to Rename
  1167. ------------------------
  1168.  
  1169.    The normal way to move a file is to copy OLD to NEW, and then issue
  1170. the normal CVS commands to remove OLD from the repository, and add NEW
  1171. to it.
  1172.  
  1173.      $ mv OLD NEW
  1174.      $ cvs remove OLD
  1175.      $ cvs add NEW
  1176.      $ cvs commit -m "Renamed OLD to NEW" OLD NEW
  1177.  
  1178.    This is the simplest way to move a file, it is not error-prone, and
  1179. it preserves the history of what was done.  Note that to access the
  1180. history of the file you must specify the old or the new name, depending
  1181. on what portion of the history you are accessing.  For example, `cvs
  1182. log OLD' will give the log up until the time of the rename.
  1183.  
  1184.    When NEW is committed its revision numbers will start again, usually
  1185. at 1.1, so if that bothers you, use the `-r rev' option to commit.  For
  1186. more information see *Note Assigning revisions::.
  1187.  
  1188. 
  1189. File: cvs.info,  Node: Inside,  Next: Rename by copying,  Prev: Outside,  Up: Moving files
  1190.  
  1191. Moving the history file
  1192. -----------------------
  1193.  
  1194.    This method is more dangerous, since it involves moving files inside
  1195. the repository.  Read this entire section before trying it out!
  1196.  
  1197.      $ cd $CVSROOT/DIR
  1198.      $ mv OLD,v NEW,v
  1199.  
  1200. Advantages:
  1201.  
  1202.    * The log of changes is maintained intact.
  1203.  
  1204.    * The revision numbers are not affected.
  1205.  
  1206. Disadvantages:
  1207.  
  1208.    * Old releases cannot easily be fetched from the repository.  (The
  1209.      file will show up as NEW even in revisions from the time before it
  1210.      was renamed).
  1211.  
  1212.    * There is no log information of when the file was renamed.
  1213.  
  1214.    * Nasty things might happen if someone accesses the history file
  1215.      while you are moving it.  Make sure no one else runs any of the CVS
  1216.      commands while you move it.
  1217.  
  1218. 
  1219. File: cvs.info,  Node: Rename by copying,  Prev: Inside,  Up: Moving files
  1220.  
  1221. Copying the history file
  1222. ------------------------
  1223.  
  1224.    This way also involves direct modifications to the repository.  It
  1225. is safe, but not without drawbacks.
  1226.  
  1227.      # Copy the RCS file inside the repository
  1228.      $ cd $CVSROOT/DIR
  1229.      $ cp OLD,v NEW,v
  1230.      # Remove the old file
  1231.      $ cd ~/DIR
  1232.      $ rm OLD
  1233.      $ cvs remove OLD
  1234.      $ cvs commit OLD
  1235.      # Remove all tags from NEW
  1236.      $ cvs update NEW
  1237.      $ cvs log NEW             # Remember the non-branch tag names
  1238.      $ cvs tag -d TAG1 NEW
  1239.      $ cvs tag -d TAG2 NEW
  1240.      ...
  1241.  
  1242.    By removing the tags you will be able to check out old revisions.
  1243.  
  1244. Advantages:
  1245.  
  1246.    * Checking out old revisions works correctly, as long as you use
  1247.      `-rTAG' and not `-DDATE' to retrieve the revisions.
  1248.  
  1249.    * The log of changes is maintained intact.
  1250.  
  1251.    * The revision numbers are not affected.
  1252.  
  1253. Disadvantages:
  1254.  
  1255.    * You cannot easily see the history of the file across the rename.
  1256.  
  1257.  
  1258.